---
title: "frappe.utils Functions Reference Guide"
space: "Frappe Framework"
url: "https://support.aakvatech.com/Frappe Framework/frappe-utility-functions-reference-guide"
updated: "2026-07-22"
---

## User Information Functions

#### Function: `get_fullname(user=None)`
**Description**: Returns the full name (first name + last name) of a user from the User DocType.

**Parameters**:

- `user` (str, optional): The user ID. Defaults to the currently logged-in user.

**Example Usage**:
```python
fullname = get_fullname("admin@example.com")
```

#### Function: `get_email_address(user=None)`
**Description**: Retrieves the email address associated with the user.

**Parameters**:

- `user` (str, optional): User ID. Defaults to current session user.

**Example Usage**:
```python
email = get_email_address("admin@example.com")
```

#### Function: `get_formatted_email(user, mail=None)`
**Description**: Returns a formatted string with full name and email in the format `John Doe <john@example.com>`.

**Parameters**:

- `user` (str): User ID.
- `mail` (str, optional): Override email address.

**Example Usage**:
```python
formatted = get_formatted_email("admin@example.com")
```

## Email Utilities

#### Function: `extract_email_id(email)`
**Description**: Extracts only the email part from a formatted email string.

**Parameters**:

- `email` (str): Formatted or raw email string.

**Example Usage**:
```python
email_id = extract_email_id("John Doe <john@example.com>")
```

#### Function: `split_emails(txt)`
**Description**: Splits a string of emails into a list, handling commas and line breaks.

**Parameters**:

- `txt` (str): Multi-email string.

**Example Usage**:
```python
emails = split_emails("a@example.com, b@example.com\nc@example.com")
```

#### Function: `sanitize_email(emails)`
**Description**: Validates and formats a list of emails into safe `Full Name <email>` format.

**Parameters**:

- `emails` (str): String of emails.

**Example Usage**:
```python
clean = sanitize_email("a@example.com, b@example.com")
```

## Validation Functions

#### Function: `validate_phone_number_with_country_code(phone_number, fieldname)`
**Description**: Validates a phone number using country code parsing.

**Parameters**:

- `phone_number` (str): Phone number to validate.
- `fieldname` (str): Name of the field in the form.

**Example Usage**:
```python
validate_phone_number_with_country_code("+255712345678", "contact_number")
```

#### Function: `validate_phone_number(phone_number, throw=False)`
**Description**: Checks whether a phone number is valid. Can raise an exception.

**Parameters**:

- `phone_number` (str): Phone number.
- `throw` (bool): Raise exception if invalid.

**Example Usage**:
```python
if validate_phone_number("+255712345678"):
    print("Valid")
```

#### Function: `validate_email_address(email_str, throw=False)`
**Description**: Validates email address format.

**Parameters**:

- `email_str` (str): Email string.
- `throw` (bool): Raise exception if invalid.

**Example Usage**:
```python
valid = validate_email_address("user@example.com")
```

#### Function: `validate_name(name, throw=False)`
**Description**: Validates personal name formats.

**Parameters**:

- `name` (str): Name string.
- `throw` (bool): Raise exception if invalid.

**Example Usage**:
```python
validate_name("John O'Reilly")
```

#### Function: `validate_url(txt, throw=False, valid_schemes=None)`
**Description**: Validates if the given string is a URL. Optionally enforces scheme.

**Parameters**:

- `txt` (str): URL string.
- `throw` (bool): Raise exception on invalid URL.
- `valid_schemes` (list or str, optional): Acceptable schemes like "http", "https".

**Example Usage**:
```python
validate_url("https://frappe.io", throw=True)
```

## Markdown & HTML Utilities

#### Function: `strip_html_tags(text)`
**Description**: Removes all HTML tags from a given string.

**Parameters**:

- `text` (str): HTML content.

**Example Usage**:
```python
clean = strip_html_tags("<p>Hello</p>")
```

#### Function: `markdown(text, sanitize=True, linkify=True)`
**Description**: Converts markdown or plain text to sanitized HTML.

**Parameters**:

- `text` (str): Markdown or HTML text.
- `sanitize` (bool): Clean HTML output.
- `linkify` (bool): Convert URLs to links.

**Example Usage**:
```python
html = markdown("# Welcome\nVisit https://frappe.io")
```

#### Function: `is_markdown(text)`
**Description**: Detects whether a string is markdown.

**Parameters**:

- `text` (str): Text content.

**Example Usage**:
```python
is_md = is_markdown("# Heading")
```

## File & Path Utilities

#### Function: `get_path(*path, **kwargs)`
**Description**: Joins a list of paths using the site path as the base.

**Parameters**:

- `*path`: List of path parts.
- `base` (str, optional): Override base path.

**Example Usage**:
```python
path = get_path("public", "files")
```

#### Function: `get_site_path(*path)`
**Description**: Joins paths under the current site's base directory.

**Parameters**:

- `*path`: Path parts.

**Example Usage**:
```python
site_path = get_site_path("public")
```

#### Function: `get_files_path(*path, is_private=False)`
**Description**: Returns full path under public or private files.

**Parameters**:

- `*path`: File path parts.
- `is_private` (bool): Use private path.

**Example Usage**:
```python
private_path = get_files_path("invoice.pdf", is_private=True)
```

#### Function: `get_file_size(path, format=False)`
**Description**: Returns file size in bytes or human-readable format.

**Parameters**:

- `path` (str): File path.
- `format` (bool): Return in readable units (KB, MB).

**Example Usage**:
```python
size = get_file_size("/path/to/file", format=True)
```

#### Function: `get_file_timestamp(fn)`
**Description**: Returns the last modified timestamp of a file.

**Parameters**:

- `fn` (str): File path.

**Example Usage**:
```python
ts = get_file_timestamp("example.txt")
```

## Shell Execution Utilities

#### Function: `execute_in_shell(cmd, verbose=False, low_priority=False, check_exit_code=False)`
**Description**: Executes a shell command and returns standard output and error output.

**Parameters**:

- `cmd` (str or list): The shell command to execute.
- `verbose` (bool): Print the output if True.
- `low_priority` (bool): Run the command with lower priority.
- `check_exit_code` (bool): Raise exception if the command fails.

**Example Usage**:
```python
err, out = execute_in_shell("ls -la", verbose=True)
```

#### Function: `touch_file(path)`
**Description**: Updates the modification time of a file or creates it if it does not exist.

**Parameters**:

- `path` (str): Path to the file.

**Example Usage**:
```python
touch_file("temp.log")
```

## JSON & Data Utilities

#### Function: `parse_json(val)`
**Description**: Parses a JSON string into a Python dictionary or returns it if already parsed.

**Parameters**:

- `val` (str or dict): JSON string or dict.

**Example Usage**:
```python
parsed = parse_json('{"key": "value"}')
```

#### Function: `safe_json_loads(*args)`
**Description**: Attempts to parse multiple JSON strings safely and returns the first valid one.

**Parameters**:

- `*args`: Multiple JSON strings.

**Example Usage**:
```python
config = safe_json_loads("invalid", '{"debug": true}')
```

#### Function: `dict_to_str(args, sep="&")`
**Description**: Converts a dictionary into a URL query string.

**Parameters**:

- `args` (dict): Dictionary to convert.
- `sep` (str): Separator for key-value pairs.

**Example Usage**:
```python
query = dict_to_str({"name": "Test", "id": 1})
```

#### Function: `list_to_str(seq, sep=", ")`
**Description**: Converts a list or sequence to a string separated by a given character.

**Parameters**:

- `seq` (list): List of elements.
- `sep` (str): Separator.

**Example Usage**:
```python
joined = list_to_str(["apple", "banana"])
```

#### Function: `get_safe_filters(filters)`
**Description**: Parses filters provided as JSON and ensures type safety.

**Parameters**:

- `filters` (str): JSON string representing filters.

**Example Usage**:
```python
safe = get_safe_filters('{"status": "Open"}')
```

#### Function: `remove_blanks(d)`
**Description**: Removes all keys with falsy values ("", None) from a dictionary.

**Parameters**:

- `d` (dict): Dictionary.

**Example Usage**:
```python
cleaned = remove_blanks({"name": "", "active": True})
```

## System Information Functions

#### Function: `get_disk_usage()`
**Description**: Returns the disk space used by the `files` directory of the site.

**Parameters**: None

**Example Usage**:
```python
disk_space = get_disk_usage()
```

#### Function: `get_site_info()`
**Description**: Returns a summary of site-level configuration and usage statistics.

**Parameters**: None

**Example Usage**:
```python
info = get_site_info()
```

#### Function: `get_installed_apps_info()`
**Description**: Retrieves installed apps along with their versions and branches.

**Parameters**: None

**Example Usage**:
```python
apps = get_installed_apps_info()
```

#### Function: `get_bench_path()`
**Description**: Gets the root path of the bench environment.

**Parameters**: None

**Example Usage**:
```python
path = get_bench_path()
```

## Decorators and Callback Management

#### Function: `@deprecated`
**Description**: Marks a function as deprecated. Will show warnings when used.
**Usage**:
```python
@deprecated
def old_function():
    pass
```

#### Class: `CallbackManager`
**Description**: Manages deferred callbacks to run after certain actions like commits.
**Methods**:
- `add(func)`: Queue a function.
- `run()`: Run all queued functions.
- `reset()`: Clear the callback queue.

**Example Usage**:
```python
cb = CallbackManager()
cb.add(lambda: print("Callback"))
cb.run()
```

## Shell Execution Utilities

#### Function: `execute_in_shell(cmd, verbose=False, low_priority=False, check_exit_code=False)`
**Description**: Executes a shell command and returns standard output and error output.

**Parameters**:

- `cmd` (str or list): The shell command to execute.
- `verbose` (bool): Print the output if True.
- `low_priority` (bool): Run the command with lower priority.
- `check_exit_code` (bool): Raise exception if the command fails.

**Example Usage**:
```python
err, out = execute_in_shell("ls -la", verbose=True)
```

#### Function: `touch_file(path)`
**Description**: Updates the modification time of a file or creates it if it does not exist.

**Parameters**:

- `path` (str): Path to the file.

**Example Usage**:
```python
touch_file("temp.log")
```

## JSON & Data Utilities

#### Function: `parse_json(val)`
**Description**: Parses a JSON string into a Python dictionary or returns it if already parsed.

**Parameters**:

- `val` (str or dict): JSON string or dict.

**Example Usage**:
```python
parsed = parse_json('{"key": "value"}')
```

#### Function: `safe_json_loads(*args)`
**Description**: Attempts to parse multiple JSON strings safely and returns the first valid one.

**Parameters**:

- `*args`: Multiple JSON strings.

**Example Usage**:
```python
config = safe_json_loads("invalid", '{"debug": true}')
```

#### Function: `dict_to_str(args, sep="&")`
**Description**: Converts a dictionary into a URL query string.

**Parameters**:

- `args` (dict): Dictionary to convert.
- `sep` (str): Separator for key-value pairs.

**Example Usage**:
```python
query = dict_to_str({"name": "Test", "id": 1})
```

#### Function: `list_to_str(seq, sep=", ")`
**Description**: Converts a list or sequence to a string separated by a given character.

**Parameters**:

- `seq` (list): List of elements.
- `sep` (str): Separator.

**Example Usage**:
```python
joined = list_to_str(["apple", "banana"])
```

#### Function: `get_safe_filters(filters)`
**Description**: Parses filters provided as JSON and ensures type safety.

**Parameters**:

- `filters` (str): JSON string representing filters.

**Example Usage**:
```python
safe = get_safe_filters('{"status": "Open"}')
```

#### Function: `remove_blanks(d)`
**Description**: Removes all keys with falsy values ("", None) from a dictionary.

**Parameters**:

- `d` (dict): Dictionary.

**Example Usage**:
```python
cleaned = remove_blanks({"name": "", "active": True})
```

## System Information Functions

#### Function: `get_disk_usage()`
**Description**: Returns the disk space used by the `files` directory of the site.

**Parameters**: None

**Example Usage**:
```python
disk_space = get_disk_usage()
```

#### Function: `get_site_info()`
**Description**: Returns a summary of site-level configuration and usage statistics.

**Parameters**: None

**Example Usage**:
```python
info = get_site_info()
```

#### Function: `get_installed_apps_info()`
**Description**: Retrieves installed apps along with their versions and branches.

**Parameters**: None

**Example Usage**:
```python
apps = get_installed_apps_info()
```

#### Function: `get_bench_path()`
**Description**: Gets the root path of the bench environment.

**Parameters**: None

**Example Usage**:
```python
path = get_bench_path()
```

## Decorators and Callback Management

#### Function: `@deprecated`
**Description**: Marks a function as deprecated. Will show warnings when used.
**Usage**:
```python
@deprecated
def old_function():
    pass
```

#### Class: `CallbackManager`
**Description**: Manages deferred callbacks to run after certain actions like commits.
**Methods**:
- `add(func)`: Queue a function.
- `run()`: Run all queued functions.
- `reset()`: Clear the callback queue.

**Example Usage**:
```python
cb = CallbackManager()
cb.add(lambda: print("Callback"))
cb.run()
```